home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / obero / oberon_lib.lha / oberon-a / source1.lha / source / Amiga / RealTime.mod < prev    next >
Text File  |  1994-08-08  |  11KB  |  356 lines
  1. (*************************************************************************
  2.  
  3.      $RCSfile: RealTime.mod $
  4.   Description: Interface to realtime.library
  5.  
  6.    Created by: fjc (Frank Copeland)
  7.     $Revision: 3.1 $
  8.       $Author: fjc $
  9.         $Date: 1994/08/08 01:18:02 $
  10.  
  11.   Includes Release 40.15
  12.  
  13.   (C) Copyright 1993 Commodore-Amiga, Inc.
  14.       All Rights Reserved
  15.  
  16.   Oberon-A Interface Copyright © 1994, Frank Copeland.
  17.   This file is part of the Oberon-A Interface.
  18.   See Oberon-A.doc for conditions of use and distribution.
  19.  
  20.   Log entries are at the end of the file.
  21.  
  22. *************************************************************************)
  23.  
  24. MODULE RealTime;
  25.  
  26. (*
  27. ** $C- CaseChk       $I- IndexChk  $L+ LongAdr   $N- NilChk
  28. ** $P- PortableCode  $R- RangeChk  $S- StackChk  $T- TypeChk
  29. ** $V- OvflChk       $Z- ZeroVars
  30. *)
  31.  
  32. IMPORT
  33.   E   := Exec,
  34.   U   := Utility,
  35.   SYS := SYSTEM;
  36.  
  37. (*
  38. **      $VER: realtime.h 40.3 (5.4.93)
  39. **
  40. **      realtime.library timing and syncing system
  41. *)
  42.  
  43. (*****************************************************************************)
  44.  
  45. CONST
  46.  
  47. (* realtime.library's idea of time is based on a clock which emits a pulse
  48.  * 1200 times a second (1.2kHz). All time values maintained by realtime.library
  49.  * are based on this number. For example, the field RealTimeBase->rtb_Time
  50.  * expresses an amount of time equivalent to (RealTimeBase->rtb_Time/TICK_FREQ)
  51.  * seconds.
  52.  *)
  53.   tickFreq * = 1200;
  54.  
  55.  
  56. (*****************************************************************************)
  57.  
  58. TYPE
  59.  
  60. (* Each Conductor represents a group of applications which wish to remain
  61.  * synchronized together.
  62.  *
  63.  * This structure must only be allocated by realtime.library and is
  64.  * READ-ONLY!
  65.  *)
  66.   ConductorPtr * = CPOINTER TO Conductor;
  67.   Conductor * = RECORD (E.Node)
  68.     reserved0 *       : E.UWORD;
  69.     players *         : E.MinList; (* this conductor's players      *)
  70.     clockTime *       : E.ULONG;   (* current time of this sequence *)
  71.     startTime *       : E.ULONG;   (* start time of this sequence   *)
  72.     externalTime *    : E.ULONG;   (* time from external unit       *)
  73.     maxExternalTime * : E.ULONG;   (* upper limit on sync'd time    *)
  74.     metronome *       : E.ULONG;   (* MetricTime highest pri node   *)
  75.     reserved1 *       : E.UWORD;
  76.     flags *           : E.WSET;    (* conductor flags               *)
  77.     state *           : E.UBYTE;   (* playing or stopped            *)
  78.   END;
  79.  
  80. CONST
  81.  
  82. (* Flag bits for Conductor.cdt_Flags *)
  83.   conductExternal * = 0;       (* clock is externally driven *)
  84.   conductGotTick *  = 1;       (* received 1st external tick *)
  85.   conductMetroSet * = 2;       (* cdt_Metronome filled in    *)
  86.   conductPrivate *  = 3;       (* conductor is private       *)
  87.  
  88. (* constants for Conductor.cdt_State and SetConductorState() *)
  89.   condStateStopped * = 0;          (* clock is stopped              *)
  90.   condStatePaused *  = 1;          (* clock is paused               *)
  91.   condStateLocate *  = 2;          (* go to 'running' when ready    *)
  92.   condStateRunning * = 3;          (* run clock NOW                 *)
  93.  
  94. (* These do not actually exist as Conductor states, but are used as additional
  95.  * arguments to SetConductorState()
  96.  *)
  97.   condStateMetric *    = -1;       (* ask high node to locate       *)
  98.   condStateShuttle *   = -2;       (* time changing but not running *)
  99.   condStateLocateSet * = -3;       (* maestro done locating         *)
  100.  
  101.  
  102. (*****************************************************************************)
  103.  
  104. TYPE
  105.  
  106. (* The Player is the connection between a Conductor and an application.
  107.  *
  108.  * This structure must only be allocated by realtime.library and is
  109.  * READ-ONLY!
  110.  *)
  111.   PlayerPtr * = CPOINTER TO Player;
  112.   Player * = RECORD (E.Node)
  113.     reserved0 *  : SHORTINT;
  114.     reserved1 *  : SHORTINT;
  115.     hook *       : U.HookPtr;     (* player's hook function       *)
  116.     source *     : ConductorPtr;  (* pointer to parent context    *)
  117.     task *       : E.TaskPtr;     (* task to signal for alarm     *)
  118.     metricTime * : LONGINT;       (* current time in app's metric *)
  119.     alarmTime *  : LONGINT;       (* time to wake up              *)
  120.     userData *   : E.APTR;        (* for application use          *)
  121.     playerID *   : E.UWORD;       (* for application use          *)
  122.     flags *      : E.WSET;        (* general Player flags         *)
  123.   END;
  124.  
  125. CONST
  126.  
  127. (* Flag bits for Player.pl_Flags *)
  128.   playerbReady * = 0;              (* player is ready to go!        *)
  129.   playerbAlarmSet * = 1;           (* alarm is set                  *)
  130.   playerbQuiet * = 2;              (* a dummy player, used for sync *)
  131.   playerbConducted * = 3;          (* give me metered time          *)
  132.   playerbExtSync * = 4;            (* granted external sync         *)
  133.  
  134.  
  135. (*****************************************************************************)
  136.  
  137. CONST
  138.  
  139. (* Tags for CreatePlayer(), SetPlayerAttrs(), and GetPlayerAttrs() *)
  140.   playerBase *         = U.tagUser + 64;
  141.   playerHook *         = playerBase+1;   (* set address of hook function *)
  142.   playerName *         = playerBase+2;   (* name of player               *)
  143.   playerPriority *     = playerBase+3;   (* priority of player           *)
  144.   playerConductor *    = playerBase+4;   (* set conductor for player     *)
  145.   playerReady *        = playerBase+5;   (* the "ready" flag             *)
  146.   playerAlarmTime *    = playerBase+12;  (* alarm time (sets PLAYERF_ALARMSET) *)
  147.   playerAlarm *        = playerBase+13;  (* sets/clears PLAYERF_ALARMSET flag  *)
  148.   playerAlarmSigTask * = playerBase+6;   (* task to signal for alarm/notify    *)
  149.   playerAlarmSigBit *  = playerBase+8;   (* signal bit for alarm (or -1) *)
  150.   playerConducted *    = playerBase+7;   (* sets/clears PLAYERF_CONDUCTED flag   *)
  151.   playerQuiet *        = playerBase+9;   (* don't process time thru this *)
  152.   playerUserData *     = playerBase+10;
  153.   playerID *           = playerBase+11;
  154.   playerExtSync *      = playerBase+14;  (* attempt/release to ext sync  *)
  155.   playerErrorCode *    = playerBase+15;  (* error return value           *)
  156.  
  157.  
  158. (*****************************************************************************)
  159.  
  160. CONST
  161.  
  162. (* Method types for messages sent via a Player's hook *)
  163.   pmTick * = 0;
  164.   pmState * = 1;
  165.   pmPosition * = 2;
  166.   pmShuttle * = 3;
  167.  
  168. TYPE
  169.  
  170.   MsgPtr * = CPOINTER TO Msg;
  171.   Msg * = RECORD
  172.     method * : E.ULONG;
  173.   END;
  174.  
  175. (* used for PM_TICK, PM_POSITION and PM_SHUTTLE methods *)
  176.   PMTimePtr * = CPOINTER TO PMTime;
  177.   PMTime * = RECORD (Msg) (* PM_TICK, PM_POSITION, or PM_SHUTTLE *)
  178.     time * :  E.ULONG;
  179.   END;
  180.  
  181. (* used for the PM_STATE method *)
  182.   PMStatePtr * = CPOINTER TO PMState;
  183.   PMState * = RECORD (Msg) (* PM_STATE *)
  184.     oldState * :  E.ULONG;
  185.   END;
  186.  
  187.  
  188. (*****************************************************************************)
  189.  
  190. CONST
  191.  
  192. (* Possible lock types for LockRealTime() *)
  193.   rtConductors * = 0;     (* conductor list *)
  194.  
  195.  
  196. (*****************************************************************************)
  197.  
  198. CONST
  199.  
  200. (* realtime.library error codes *)
  201.   eNoMemory *    = 801;  (* memory allocation failed      *)
  202.   eNoConductor * = 802;  (* player needs a conductor      *)
  203.   eNoTimer *     = 803;  (* timer (CIA) allocation failed *)
  204.   ePlaying *     = 804;  (* can't shuttle while playing   *)
  205.  
  206.  
  207. (*****************************************************************************)
  208.  
  209. TYPE
  210.  
  211. (* OpenLibrary("realtime.library",0) returns a pointer to this structure.
  212.  * All fields are READ-ONLY.
  213.  *)
  214.   RealTimeBasePtr * = CPOINTER TO RealTimeBase;
  215.   RealTimeBase * = RECORD (E.Library)
  216.     reserved0 - : ARRAY 2 OF E.UBYTE;
  217.  
  218.     time -      : E.ULONG;   (* current time                         *)
  219.     timeFrac -  : E.ULONG;   (* fixed-point fraction part of time    *)
  220.     reserved1 - : E.UWORD;
  221.     tickErr -   : INTEGER;   (* nanosecond error from ideal Tick     *)
  222.   END;                       (* length to real tick length           *)
  223.  
  224. CONST
  225.  
  226. (* Actual tick length is: 1/TICK_FREQ + rtb_TickErr/1e9 *)
  227.  
  228.   realTimeTickErrMin * = -705;
  229.   realTimeTickErrMax * = 705;
  230.  
  231.  
  232. (*****************************************************************************)
  233.  
  234. (*-- Library Base variable --------------------------------------------*)
  235.  
  236. CONST
  237.  
  238.   name * = "realtime.library";
  239.  
  240. VAR
  241.  
  242.   base* : RealTimeBasePtr;
  243.  
  244.  
  245. (*-- Library Functions ------------------------------------------------*)
  246.  
  247. (*
  248. **      $VER: realtime_protos.h 40.1 (16.3.93)
  249. *)
  250.  
  251. (*--- functions in V37 or higher (Release 2.04) ---*)
  252.  
  253. (* Locks *)
  254.  
  255. LIBCALL (base : RealTimeBasePtr) LockRealTime *
  256.   ( lockType [0] : E.ULONG )
  257.   : E.APTR;
  258.   -30;
  259.  
  260. LIBCALL (base : RealTimeBasePtr) UnlockRealTime *
  261.   ( lock [8] : E.APTR );
  262.   -36;
  263.  
  264. (* Conductor *)
  265.  
  266. LIBCALL (base : RealTimeBasePtr) CreatePlayerA *
  267.   ( tagList [8] : ARRAY OF U.TagItem )
  268.   : PlayerPtr;
  269.   -42;
  270.  
  271. LIBCALL (base : RealTimeBasePtr) CreatePlayer *
  272.   ( tagList [8]..: U.Tag )
  273.   : PlayerPtr;
  274.   -42;
  275.  
  276. LIBCALL (base : RealTimeBasePtr) DeletePlayer *
  277.   ( player [8] : PlayerPtr );
  278.   -48;
  279.  
  280. LIBCALL (base : RealTimeBasePtr) SetPlayerAttrsA *
  281.   ( player  [8] : PlayerPtr;
  282.     tagList [9] : ARRAY OF U.TagItem )
  283.   : BOOLEAN;
  284.   -54;
  285.  
  286. LIBCALL (base : RealTimeBasePtr) SetPlayerAttrs *
  287.   ( player  [8]  : PlayerPtr;
  288.     tagList [9]..: U.Tag )
  289.   : BOOLEAN;
  290.   -54;
  291.  
  292. LIBCALL (base : RealTimeBasePtr) SetConductorState *
  293.   ( player [8] : PlayerPtr;
  294.     state [0]  : E.ULONG;
  295.     time [1]   : LONGINT )
  296.   : LONGINT;
  297.   -60;
  298.  
  299. LIBCALL (base : RealTimeBasePtr) ExternalSync *
  300.   ( player  [8] : PlayerPtr;
  301.     minTime [0] : LONGINT;
  302.     maxTime [1] : LONGINT )
  303.   : BOOLEAN;
  304.   -66;
  305.  
  306. LIBCALL (base : RealTimeBasePtr) NextConductor *
  307.   ( previousConductor [8] : ConductorPtr )
  308.   : ConductorPtr;
  309.   -72;
  310.  
  311. LIBCALL (base : RealTimeBasePtr) FindConductor *
  312.   ( name [8] : ARRAY OF CHAR )
  313.   : ConductorPtr;
  314.   -78;
  315.  
  316. LIBCALL (base : RealTimeBasePtr) GetPlayerAttrsA *
  317.   ( player  [8] : PlayerPtr;
  318.     tagList [9] : ARRAY OF U.TagItem )
  319.   : E.ULONG;
  320.   -84;
  321.  
  322. LIBCALL (base : RealTimeBasePtr) GetPlayerAttrs *
  323.   ( player  [8]  : PlayerPtr;
  324.     tagList [9]..: U.Tag )
  325.   : E.ULONG;
  326.   -84;
  327.  
  328. (*-- Library Base variable --------------------------------------------*)
  329. (* $L- *)
  330.  
  331. (*-----------------------------------*)
  332. PROCEDURE* CloseLib ();
  333.  
  334. BEGIN (* CloseLib *)
  335.   IF base # NIL THEN E.base.CloseLibrary (base) END
  336. END CloseLib;
  337.  
  338. (*-----------------------------------*)
  339. PROCEDURE OpenLib * (mustOpen : BOOLEAN);
  340.  
  341. BEGIN (* OpenLib *)
  342.   IF base = NIL THEN
  343.     base :=
  344.       SYS.VAL (
  345.         RealTimeBasePtr,
  346.         E.base.OpenLibrary (name, E.libraryMinimum));
  347.     IF base # NIL THEN SYS.SETCLEANUP (CloseLib)
  348.     ELSIF mustOpen THEN HALT (100)
  349.     END;
  350.   END;
  351. END OpenLib;
  352.  
  353. BEGIN
  354.   base := NIL
  355. END RealTime.
  356.